Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::ActivityConcept Class Referenceabstract

Base class for Activity classes. More...

#include <kanzi/ui/node/concept/activity/activity_concept.hpp>

Inheritance diagram for kanzi::ActivityConcept:
[legend]

Classes

class  ActivityInternalMessageArguments
 Class for all the internal Activity messages that do not require any message arguments. More...
 
class  ActivityMessageArguments
 Message arguments that hold the name of the Activity included in the message. More...
 
class  StartActivationInternalMessageArguments
 Message arguments for the StartActivationInternalMessage. More...
 
class  StatusChangedInternalMessageArguments
 Message arguments for internal Activity messages related to Activity status changes. More...
 
class  StatusChangedMessageArguments
 Message arguments for the StatusChangedMessage. More...
 

Public Types

enum  Status { Status::Active, Status::Inactive, Status::Activating, Status::Deactivating }
 Defines possible states of an Activity. More...
 

Public Member Functions

void cancelWaitBeforeFocus ()
 Makes an Activity no longer wait for any pending activations. More...
 
virtual bool collectActivatingDescendantActivities ()=0
 Returns whether any Activities are activating in the descendant Activity Hosts whose parent Activity this Activity is. More...
 
virtual void enableFocusGain (bool enable)=0
 Enables an overlay scope Activity to gain focus automatically when activated. More...
 
virtual void enableFocusRecovery (bool enable)=0
 Enables Kanzi to automatically recover focus when an overlay scope Activity is deactivated. More...
 
virtual void enableInput (bool enable)=0
 Enables input handling for an Activity that is an overlay-type focus scope. More...
 
virtual NodegetNode ()=0
 Gets the underlying Node object. More...
 
virtual const NodegetNode () const =0
 Gets the underlying Node object. More...
 
virtual ActivityConceptgetParentActivity ()=0
 Returns the parent Activity. More...
 
optional< string > getPathToActivity (ActivityConcept *activity) const
 Returns a path from this Activity to a given Activity, if that Activity is a descendant node of this Activity. More...
 
virtual bool isAutoClosingBecauseFocusMove () const =0
 Returns whether an Activity is deactivating because it is an auto-closing overlay scope and focus moves below it. More...
 
bool isWaitingActivationsBeforeFocus () const
 Returns whether an Activity is waiting for its descendant Activities to activate before Kanzi applies the focus policy to the activated Activity. More...
 
bool isWaitingForActivation (ActivityConcept *activity) const
 Returns whether an Activity is waiting for the activation of a given Activity. More...
 
virtual void notifyPendingActivationBeforeFocusFinished (string_view activityName)=0
 Notifies the Activity that a descendant Activity, for whose activation this Activity waited, finished activating. More...
 
virtual void restoreLastFocusedNode ()=0
 Restores the focus to a child node of this Activity, if this Activity: More...
 
virtual void setLastFocusedNodePath ()=0
 Sets the last focused node path of this Activity to the currently focused child node, if the Activity: More...
 
virtual void tryRestoreLastFocusedPathCompletely (const Node *candidateChild)=0
 Tries to recursively restore the last focused node path in this and each ancestor Activity. More...
 
virtual ~ActivityConcept ()=default
 Destructor. More...
 

Static Public Member Functions

template<typename Type >
static bool isActivity (const Type &object)
 Returns whether an object is an Activity. More...
 
static bool isActivityMetaclass (const Metaclass *metaclass)
 Checks whether the given Metaclass is an ActivityConcept metaclass or contains it as a mixin metaclass. More...
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 

Static Public Attributes

static NodeWeakPtr s_activationTargetActivity
 The Activity that is the activation target. More...
 
Properties
static PropertyType< StatusStatusProperty
 Specifies the status of this Activity. More...
 
static PropertyType< float > DummyStateManagerProperty
 Lack of a queuing mechanism for incoming messages from an Activity Host can cause Kanzi to enter a recursive call in the setProperty(). More...
 
static PropertyType< bool > ActivatedByActivationModifierProperty
 Specifies whether the activation of an Activity is requested by modifier bindings callbacks of an ApplyAction of a DataTrigger. More...
 
static PropertyType< bool > SaveLastFocusedNodeProperty
 Indicates whether to serialize the last focused child node of a focus scope Activity and restore the focus on deserialization. More...
 
Messages
static MessageType< StatusChangedMessageArgumentsStatusChangedMessage
 Subscribe to this message to receive notifications when the ActivityConcept::Status of this Activity changes. More...
 
static MessageType< ActivityMessageArgumentsActivityActivatingMessage
 Subscribe to this message to receive notifications when this Activity is in the activating state. More...
 
static MessageType< ActivityMessageArgumentsActivityActivatedMessage
 Subscribe to this message to receive notifications when this Activity is activated. More...
 
static MessageType< ActivityMessageArgumentsActivityDeactivatingMessage
 Subscribe to this message to receive notifications when this Activity is in the deactivating state. More...
 
static MessageType< ActivityMessageArgumentsActivityDeactivatedMessage
 Subscribe to this message to receive notifications when this Activity is deactivated. More...
 
Internal Messages
static MessageType< StartActivationInternalMessageArgumentsStartActivationInternalMessage
 Internal message sent by an Activity Host to the Activity to initialize the resources of the Activity. More...
 
static MessageType< ActivityInternalMessageArgumentsStartDeactivationInternalMessage
 Internal message sent by an Activity Host to the Activity to deactivate the Activity. More...
 
static MessageType< StatusChangedInternalMessageArgumentsReadyForActivationAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished initializing its resources. More...
 
static MessageType< ActivityInternalMessageArgumentsStartParallelActivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the parallel activation animation of the Activity. More...
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedParallelActivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel activation animation of the Activity. More...
 
static MessageType< ActivityInternalMessageArgumentsStartExclusiveActivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the exclusive activation animation of the Activity. More...
 
static MessageType< ActivityInternalMessageArgumentsStartExclusiveDeactivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the exclusive deactivation animation of the Activity. More...
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedExclusiveDeactivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the exclusive deactivation animation of the Activity. More...
 
static MessageType< ActivityInternalMessageArgumentsStartParallelDeactivatingAnimationInternalMessage
 Internal message sent by an Activity Host to the Activity to start the parallel deactivation animation of the Activity. More...
 
static MessageType< StatusChangedInternalMessageArgumentsFinishedParallelDeactivatingAnimationInternalMessage
 Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel deactivation animation of the Activity. More...
 

Protected Attributes

vector< string > m_pendingActivationsBeforeFocus
 The paths of the activating Activities that this Activity is waiting to be activated. More...
 

Detailed Description

Base class for Activity classes.

This class defines common types, properties, and messages for Activity classes.

See also
Activity2D, Activity3D

Member Enumeration Documentation

Defines possible states of an Activity.

Activity Host nodes can activate and deactivate their child Activities. This enumeration defines the possible states of an Activity during the the process of activation and deactivation. You can use this functionality to react to changes in Activity status in your application code and in Kanzi Studio.

See also
Activity, StatusProperty
Enumerator
Active 

The Activity is active.

In an Exclusive Activity Host only one child Activity can be in the Active state at a time. In a Parallel Activity Host more than one Activity can be in the Active state at the same time, therefore any Activity can be in any state.

Inactive 

The Activity is inactive.

Inactive Activities do not show their content.

Activating 

The Activity is transitioning into the active state.

In an Exclusive Activity Host while one Activity is in Activating state, another Activity can be in the Deactivating state at the same time. In a Parallel Activity Host more than one Activity can be in the Active state at the same time, therefore any Activity can be in any state.

Deactivating 

The Activity is transitioning into the inactive state.

In an Exclusive Activity Host while one Activity is in Deactivating state, another Activity can at the same time be in the Activating state. In a Parallel Activity Host more than one Activity can be in the Active state at the same time, therefore any Activity can be in any state.

Constructor & Destructor Documentation

virtual kanzi::ActivityConcept::~ActivityConcept ( )
virtualdefault

Destructor.

Member Function Documentation

static PropertyTypeEditorInfoSharedPtr kanzi::ActivityConcept::makeEditorInfo ( )
static
virtual Node* kanzi::ActivityConcept::getNode ( )
pure virtual
virtual const Node* kanzi::ActivityConcept::getNode ( ) const
pure virtual
virtual void kanzi::ActivityConcept::restoreLastFocusedNode ( )
pure virtual

Restores the focus to a child node of this Activity, if this Activity:

  • Is a focus scope node
  • Has serialized the last focused node
  • The serialized last focused node is a focusable node and is not an Activity

If Kanzi successfully restores the focus, it clears the value of the Kanzi internal property FocusScopeCore::LastFocusedNodePathProperty.

Since
Kanzi 3.9.2. Moved the function declaration and definition from ActivityElement to ActivityConcept and to ActivityConceptImpl.

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual void kanzi::ActivityConcept::setLastFocusedNodePath ( )
pure virtual

Sets the last focused node path of this Activity to the currently focused child node, if the Activity:

Since
Kanzi 3.9.2. Moved the function declaration and definition from ActivityElement to ActivityConcept and to ActivityConceptImpl.

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual void kanzi::ActivityConcept::tryRestoreLastFocusedPathCompletely ( const Node candidateChild)
pure virtual

Tries to recursively restore the last focused node path in this and each ancestor Activity.

Parameters
candidateChildThe child Activity where the last focused node path of this Activity is pointing, in order for the restoring to succeed.
Since
Kanzi 3.9.2

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual ActivityConcept* kanzi::ActivityConcept::getParentActivity ( )
pure virtual

Returns the parent Activity.

Returns
The parent Activity. If this Activity is the top-most Activity in the Activity tree, returns nullptr.
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual bool kanzi::ActivityConcept::collectActivatingDescendantActivities ( )
pure virtual

Returns whether any Activities are activating in the descendant Activity Hosts whose parent Activity this Activity is.

Returns
If there is at least one activating descendant Activity, true, otherwise false.
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual void kanzi::ActivityConcept::notifyPendingActivationBeforeFocusFinished ( string_view  activityName)
pure virtual

Notifies the Activity that a descendant Activity, for whose activation this Activity waited, finished activating.

Parameters
activityNameName of the Activity that activated.
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

optional<string> kanzi::ActivityConcept::getPathToActivity ( ActivityConcept activity) const

Returns a path from this Activity to a given Activity, if that Activity is a descendant node of this Activity.

Returns
If activity is a descendant node of this Activity, returns the path from this Activity to activity. If activity is not a descendant node of this Activity, returns nullopt.
Since
Kanzi 3.9.4
bool kanzi::ActivityConcept::isWaitingForActivation ( ActivityConcept activity) const

Returns whether an Activity is waiting for the activation of a given Activity.

Returns
If the Activity is waiting for the activation of activity, true, otherwise false.
Since
Kanzi 3.9.4
bool kanzi::ActivityConcept::isWaitingActivationsBeforeFocus ( ) const

Returns whether an Activity is waiting for its descendant Activities to activate before Kanzi applies the focus policy to the activated Activity.

Returns
If an Activity is waiting for descendant Activities to activate before Kanzi applies the focus policy to the activated Activity, true, otherwise false.
See also
ExclusiveActivityHostConcept::ExclusiveActivityHostFocusingPolicy, ParallelActivityHostConcept::ParallelActivityHostFocusingPolicy
Since
Kanzi 3.9.4
void kanzi::ActivityConcept::cancelWaitBeforeFocus ( )

Makes an Activity no longer wait for any pending activations.

Call this function when the Activity is no longer the activation target or when the Activity is able to restore the last-focused node and no longer needs to wait for any other Activity to finish activation.

See also
ActivityConcept::s_activationTargetActivity
Since
Kanzi 3.9.4
virtual void kanzi::ActivityConcept::enableFocusRecovery ( bool  enable)
pure virtual

Enables Kanzi to automatically recover focus when an overlay scope Activity is deactivated.

To make an Activity an overlay scope, set its FocusManager::FocusScopeTypeProperty to FocusScopeType::Modal, FocusScopeType::Modeless, FocusScopeType::AutoClosingModal, or FocusScopeType::AutoClosingModeless.

Parameters
enableTo enable automatic focus recovery by setting focus to another overlay when an overlay Activity is deactivated, set to true. To disable automatic focus recovery when an overlay Activity is deactivated, set to false.
See also
FocusManager, OverlayScope
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual void kanzi::ActivityConcept::enableFocusGain ( bool  enable)
pure virtual

Enables an overlay scope Activity to gain focus automatically when activated.

To make an Activity an overlay scope, set its FocusManager::FocusScopeTypeProperty to FocusScopeType::Modal, FocusScopeType::Modeless, FocusScopeType::AutoClosingModal, or FocusScopeType::AutoClosingModeless.

Parameters
enableTo enable automatic focus gain when an overlay scope Activity is activated, set to true. To disable automatic focus gain when an overlay scope Activity is activated, set to false.
See also
FocusManager, OverlayScope
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual void kanzi::ActivityConcept::enableInput ( bool  enable)
pure virtual

Enables input handling for an Activity that is an overlay-type focus scope.

To make an Activity an overlay-type focus scope, set its FocusManager::FocusScopeTypeProperty to FocusScopeType::Modal, FocusScopeType::Modeless, FocusScopeType::AutoClosingModal, or FocusScopeType::AutoClosingModeless.

Parameters
enableTo enable input handling, set to true. To disable input handling, set to false.
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

virtual bool kanzi::ActivityConcept::isAutoClosingBecauseFocusMove ( ) const
pure virtual

Returns whether an Activity is deactivating because it is an auto-closing overlay scope and focus moves below it.

To make an Activity an auto-closing overlay scope, set its FocusManager::FocusScopeTypeProperty to FocusScopeType::AutoClosingModal or FocusScopeType::AutoClosingModeless.

Returns
If an Activity is deactivating because it is an auto-closing overlay scope and focus moves below it, true, otherwise false.
See also
FocusManager, OverlayScope
Since
Kanzi 3.9.4

Implemented in kanzi::ActivityConceptImpl< TBaseClass, TDerivedClass >, kanzi::ActivityConceptImpl< ContentLayout2D, Activity2D >, and kanzi::ActivityConceptImpl< ContentLayout3D, Activity3D >.

template<typename Type >
static bool kanzi::ActivityConcept::isActivity ( const Type &  object)
inlinestatic

Returns whether an object is an Activity.

Parameters
objectObject for which you want to check whether it is an Activity.
Returns
If the object is an Activity, returns true, otherwise false.
Since
Kanzi 3.9.2
static bool kanzi::ActivityConcept::isActivityMetaclass ( const Metaclass metaclass)
inlinestatic

Checks whether the given Metaclass is an ActivityConcept metaclass or contains it as a mixin metaclass.

Parameters
metaclassThe metaclass to check.
Returns
If the given metaclass is an ActivityConcept metaclass or contains it as a mixin metaclass, returns true, otherwise false.
Since
Kanzi 3.9.3

Member Data Documentation

PropertyType<Status> kanzi::ActivityConcept::StatusProperty
static

Specifies the status of this Activity.

PropertyType<float> kanzi::ActivityConcept::DummyStateManagerProperty
static

Lack of a queuing mechanism for incoming messages from an Activity Host can cause Kanzi to enter a recursive call in the setProperty().

A temporary solution to this is the DummyStateManagerProperty that Kanzi sets in states with different values, and adds an any-to-any transition with the duration of 1 millisecond.

PropertyType<bool> kanzi::ActivityConcept::ActivatedByActivationModifierProperty
static

Specifies whether the activation of an Activity is requested by modifier bindings callbacks of an ApplyAction of a DataTrigger.

Kanzi uses this property internally to disable serialization and deserialization of the activation status for such Activities.

Since
Kanzi 3.9.0
PropertyType<bool> kanzi::ActivityConcept::SaveLastFocusedNodeProperty
static

Indicates whether to serialize the last focused child node of a focus scope Activity and restore the focus on deserialization.

If an Activity is a focus scope, add and set this property to True when you want to save and restore the focus from a serialized Activity and its focus scope.

Since
Kanzi 3.9.0
MessageType<StatusChangedMessageArguments> kanzi::ActivityConcept::StatusChangedMessage
static

Subscribe to this message to receive notifications when the ActivityConcept::Status of this Activity changes.

MessageType<ActivityMessageArguments> kanzi::ActivityConcept::ActivityActivatingMessage
static

Subscribe to this message to receive notifications when this Activity is in the activating state.

Since
Kanzi 3.9.1.
MessageType<ActivityMessageArguments> kanzi::ActivityConcept::ActivityActivatedMessage
static

Subscribe to this message to receive notifications when this Activity is activated.

Since
Kanzi 3.9.1.
MessageType<ActivityMessageArguments> kanzi::ActivityConcept::ActivityDeactivatingMessage
static

Subscribe to this message to receive notifications when this Activity is in the deactivating state.

Since
Kanzi 3.9.1.
MessageType<ActivityMessageArguments> kanzi::ActivityConcept::ActivityDeactivatedMessage
static

Subscribe to this message to receive notifications when this Activity is deactivated.

Since
Kanzi 3.9.1.
MessageType<StartActivationInternalMessageArguments> kanzi::ActivityConcept::StartActivationInternalMessage
static

Internal message sent by an Activity Host to the Activity to initialize the resources of the Activity.

MessageType<ActivityInternalMessageArguments> kanzi::ActivityConcept::StartDeactivationInternalMessage
static

Internal message sent by an Activity Host to the Activity to deactivate the Activity.

Since
Kanzi 3.9.1. Renamed DeactivateInternalMessage to StartDeactivationInternalMessage.
MessageType<StatusChangedInternalMessageArguments> kanzi::ActivityConcept::ReadyForActivationAnimationInternalMessage
static

Internal message sent by the Activity to its parent Activity Host when the Activity has finished initializing its resources.

MessageType<ActivityInternalMessageArguments> kanzi::ActivityConcept::StartParallelActivatingAnimationInternalMessage
static

Internal message sent by an Activity Host to the Activity to start the parallel activation animation of the Activity.

MessageType<StatusChangedInternalMessageArguments> kanzi::ActivityConcept::FinishedParallelActivatingAnimationInternalMessage
static

Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel activation animation of the Activity.

MessageType<ActivityInternalMessageArguments> kanzi::ActivityConcept::StartExclusiveActivatingAnimationInternalMessage
static

Internal message sent by an Activity Host to the Activity to start the exclusive activation animation of the Activity.

MessageType<ActivityInternalMessageArguments> kanzi::ActivityConcept::StartExclusiveDeactivatingAnimationInternalMessage
static

Internal message sent by an Activity Host to the Activity to start the exclusive deactivation animation of the Activity.

MessageType<StatusChangedInternalMessageArguments> kanzi::ActivityConcept::FinishedExclusiveDeactivatingAnimationInternalMessage
static

Internal message sent by the Activity to its parent Activity Host when the Activity has finished the exclusive deactivation animation of the Activity.

MessageType<ActivityInternalMessageArguments> kanzi::ActivityConcept::StartParallelDeactivatingAnimationInternalMessage
static

Internal message sent by an Activity Host to the Activity to start the parallel deactivation animation of the Activity.

MessageType<StatusChangedInternalMessageArguments> kanzi::ActivityConcept::FinishedParallelDeactivatingAnimationInternalMessage
static

Internal message sent by the Activity to its parent Activity Host when the Activity has finished the parallel deactivation animation of the Activity.

NodeWeakPtr kanzi::ActivityConcept::s_activationTargetActivity
static

The Activity that is the activation target.

Kanzi waits for descendant Activities to activate until the last-focused node of the activating Activity tree finishes loading. After that Kanzi applies the focusing policy of the activation target. The activation target is the Activity that the application logic specifically requests to be activated. Any other Activities that Kanzi activates as a side effect are not activation target Activities and Kanzi does not consider their focusing policy this time.

vector<string> kanzi::ActivityConcept::m_pendingActivationsBeforeFocus
protected

The paths of the activating Activities that this Activity is waiting to be activated.

Since
Kanzi 3.9.4

The documentation for this class was generated from the following file: